Release 10.1A: OpenEdge Development:
Progress 4GL Reference

DEFINE VARIABLE statement

Defines a variable for use within one or more procedures, or defines a variable as a data member within a class.

Syntax

DEFINE   { [ [ NEW [ GLOBAL ] ] SHARED ] | [ PRIVATE | PROTECTED | PUBLIC ] }   VARIABLE variable-name   {  AS datatype    | AS [ CLASS ] { type-name }    | LIKE field }   [ BGCOLOR expression ] [ COLUMN-LABEL label ] [ CONTEXT-HELP-ID expression ] [ DCOLOR expression ] [ DECIMALS n ] [ DROP-TARGET ] [ EXTENT [ expression ] ] [ FONT expression ] [ FGCOLOR expression ] [ FORMAT string ] [ INITIAL { constant | { [ constant [ , constant ] ... ] } } ] [ LABEL string [ , string ] ... ] [ MOUSE-POINTER expression ]   [ NO-UNDO ]   [ [ NOT ] CASE-SENSITIVE ] [ PFCOLOR expression ] { [ view-as-phrase ] } { [ trigger-phrase ] }

NEW SHARED VARIABLE variable-name

Defines and identifies a variable to be shared by a procedure called directly or indirectly by the current procedure. The called procedure must name the same variable in a DEFINE SHARED VARIABLE statement.

NEW GLOBAL SHARED VARIABLE variable-name

Defines and identifies a variable that can be used by any procedure that names that variable using the DEFINE SHARED VARIABLE statement. The value of a global shared variable remains available throughout an OpenEdge session.

SHARED VARIABLE variable-name

Defines and identifies a variable that was created by another procedure that used the DEFINE NEW SHARED VARIABLE or DEFINE NEW GLOBAL SHARED VARIABLE statement.

[ PRIVATE | PROTECTED | PUBLIC ] VARIABLE variable-name

Defines and identifies a variable as a data member for a class, and optionally specifies an access mode for that data member. Do not specify an access mode when defining a variable for a method within a class.

The variable data member name must be unique among all data members in the defining class and its inherited class hierarchy.

PRIVATE data members can be accessed only by the defining class. PROTECTED data members can be accessed by the defining class and any of its inheriting classes. PUBLIC data members can be accessed by the defining class, any of its inheriting classes, and any class or procedure that instantiates that class. The default access mode is PRIVATE.

Note: These options are applicable only when defining a data member for a class in a class definition (.cls) file.

VARIABLE variable-name

Defines and identifies a variable whose value is available only within the current procedure, or a method within a class.

AS datatype

Indicates the data type of the variable you are defining. The data types are CHARACTER, COM-HANDLE, DATE, DATETIME, DATETIME-TZ, DECIMAL, HANDLE, INTEGER, LONGCHAR, LOGICAL, MEMPTR, RAW, RECID, ROWID, and WIDGET-HANDLE.

AS [ CLASS ] { type-name }

Defines an object reference variable for the specified class or interface. The default value of the variable is the Unknown value (?).

You use this object reference variable with the NEW statement to create a new instance of a class. You access a class object instance, as well as its data members and methods, using this object reference variable. For more information about the NEW statement, see the NEW statement reference entry in this book.

Note: You can define an object reference variable for an interface, which lets you access the interface or a class that implements the interface, but you cannot create an instance of an interface with the NEW statement.

type-name

A character string that specifies the type name of the class, a subclass of the class, or the interface for which this object reference variable is defined. Specify a type name using the package.class-name syntax as described in the Type-name syntax reference entry in this book.

If the specified class or interface type name conflicts with an abbreviation of a built-in Progress data type name, such as INT for INTEGER, you must specify the CLASS keyword.

LIKE field

Indicates the name of the variable, database field, temporary table field, or work table field whose characteristics you want to use for the variable you are defining. If you name a variable with this option, you must have defined that variable earlier in the procedure. You can override the format, label, initial value, decimals, and extent of the variable or database field by using the FORMAT, LABEL, COLUMN-LABEL, INITIAL, DECIMALS, EXTENT, and VIEW-AS options. If you do not use these options, the variable takes on the characteristics of the variable or database field you name.

If field has help and validate options defined, the variable you are defining does not inherit those characteristics.

If you reference a database field in a LIKE option in a DEFINE VARIABLE statement, DEFINE TEMP-TABLE statement, DEFINE WORK-TABLE statement, or format phrase, the database containing the referenced field must be connected at both compile time and runtime. Therefore, use the LIKE option with caution.

BGCOLOR expression

Specifies a background color for the variable in graphical interfaces. This option is ignored in character interfaces.

[ NOT ] CASE-SENSITIVE

CASE-SENSITIVE indicates that the value stored for a character variable is case sensitive, and that all comparisons operations involving the variable are case sensitive. If you do not use this option, Progress comparisons are usually case insensitive. If you define a variable LIKE another field of variable, the new variable inherits case sensitivity. Use [NOT] CASE-SENSITIVE to override this default.

COLUMN-LABEL label

Names the label you want to display above the variable data in a frame that uses column labels. If you want the label to use more than one line (a stacked label), use an exclamation point (!) in the label to indicate where to break the line.

r-collbl.p

DEFINE VARIABLE credit-percent AS INTEGER COLUMN-LABEL "Enter !percentage!increase ". FOR EACH customer: DISPLAY name credit-limit. SET credit-percent. credit-limit = (credit-limit * (credit-percent / 100)) + credit-limit. DISPLAY credit-limit @ new-credit LIKE credit-limit LABEL "New max cred". END.

If you want to use the exclamation point (!) as one of the characters in a column label, use two exclamation points (!!).

Progress does not display column labels if you use the SIDE-LABELS or NO-LABELS options with the Frame phrase.

If you define a variable to be LIKE a field, and that field has a column label in the Data Dictionary, the variable inherits that column label.

CONTEXT-HELP-ID expression

An integer value that specifies the identifier of the help topic for this variable in a help file specified at the session, window or dialog box level using the CONTEXT-HELP-FILE attribute.

DCOLOR expression

Specifies the display color for the variable in character interfaces. This option is ignored in graphical interfaces.

DECIMALS n

Specifies the number of decimal places to store for a DECIMAL variable, where n is an integer constant. When you define a variable AS DECIMAL, Progress automatically stores up to 10 decimal places for the value of that variable. Use the DECIMALS option to store a smaller number of decimal places. The DECIMALS option has nothing to do with the display format of the variable, just the storage format.

If you use the LIKE option to name a field whose definition you want to use to define a variable, Progress uses the number of decimals in the field definition to determine how many decimal places to store for the variable.

DROP-TARGET

Indicates whether you want to be able to drop a file onto the object.

The following example shows setting the DROP-TARGET option for a variable:

DEFINE VARIABLE fill-in-1 AS CHARACTER DROP-TARGET.

EXTENT [ expression ]

Specifies a determinate array variable (which has a defined number of elements) or an indeterminate array variable (which has an undefined number of elements). To define a determinate array variable, specify the EXTENT option with the expression argument. This optional argument evaluates to an integer value that represents an extent for the array variable. To define an indeterminate array variable, specify the EXTENT option without the expression argument.

If you want to define a variable that is like an array variable or field, using the LIKE option, but you do not want the variable to be an array, you can use EXTENT 0 to indicate a non-array field.

If you are using the AS datatype option and you do not use the EXTENT option (or you specify expression as 0), the variable is not an array variable. If you are using the LIKE field option and you do not use the EXTENT option, the variable uses the extent defined for the database field you name (if any).

Note: You cannot define an array variable as a PUBLIC data member of a class.

FGCOLOR expression

Specifies a foreground color for the variable in graphical interfaces. This option is ignored in character interfaces.

FONT expression

Specifies a font for the variable.

FORMAT string

The data format of the variable you define. If you use the AS datatype option and you do not use FORMAT string, the variable uses the default format for its data type. Table 29 lists the default data formats for the data types.

Table 29: Default display formats

Data type	Default display format
BLOB1	See the footnote at the end of this table
CHARACTER	x(8)
CLASS3	>>>>>>9
CLOB1	See the footnote at the end of this table
COM-HANDLE	>>>>>>9
DATE	99/99/99
DATETIME	99/99/9999 HH:MM:SS.SSS
DATETIME-TZ	99/99/9999 HH:MM:SS.SSS+HH:MM
DECIMAL	->>,>>9.99
HANDLE2	>>>>>>9
INTEGER	->,>>>,>>9
LOGICAL	yes/no
LONGCHAR1	See the footnote at the end of this table
MEMPTR1	See the footnote at the end of this table
RAW1	See the footnote at the end of this table
RECID	>>>>>>9
ROWID1	See the footnote at the end of this table
WIDGET-HANDLE2	>>>>>>9
You cannot display a BLOB, CLOB, MEMPTR, RAW, or ROWID value directly. However, you can convert a MEMPTR, RAW, or ROWID value to a character string representation using the STRING function and display the result. You can also convert a BLOB to a MEMPTR, and then use the STRING function. A MEMPTR or RAW value converts to decimal integer string. A ROWID value converts to a hexadecimal string, “0xhexdigits,” where hexdigits is any number of characters “0" through “9" and “A” through “F”. You can display a CLOB field by converting it to a LONGCHAR, and displaying the LONGCHAR using the VIEW-AS EDITOR LARGE phrase only. To display a HANDLE or WIDGET-HANDLE, you must first convert it using the INTEGER function and display the result. To display a CLASS, you must first convert it using the INTEGER or STRING function and display the result.

See OpenEdge Development: Progress 4GL Handbook for more information on data formatting.

If you use the LIKE field option and you do not use the FORMAT string option, the variable uses the format defined for the database field you name. You must enclose the string in quotes.

INITIAL { constant | [ constant [ , constant ] . . . ] }

The initial value of the variable you want to define. If you use the AS datatype option and you do not use the INITIAL constant option, the default is the initial value for the data type of the variable.

When you define an array variable, you can supply initial values for each element in the array. For example:

DEFINE VARIABLE array-var AS CHARACTER EXTENT 3 INITIAL ["Add","Delete","Update"].

If you do not supply enough values to fill up the elements of the array, Progress puts the last value you named into the remaining elements of the array. If you supply too many values, Progress returns an error message.

If you define a variable as an indeterminate array, and you supply initial values for elements in the array, Progress fixes the number of elements in the array and treats the fixed indeterminate array as a determinate array. For example, the arrays defined by the following statements are equivalent:

DEFINE VARIABLE x AS INT EXTENT INIT [1,2,3]. DEFINE VARIABLE x AS INT EXTENT 3 INIT [1,2,3]

Table 30 lists the default initial values for the various variable data types.

Table 30: Default variable initial values

Data type	Default initial value
CHARACTER	"" (an empty string)
CLASS	Unknown value (?)
COM-HANDLE	Unknown value (?)
DATE	Unknown value (?)       (displays as blanks)
DATETIME	Unknown value (?)
DATETIME-TZ	Unknown value (?)
DECIMAL	0
HANDLE	Unknown value (?)
INTEGER	0
LOGICAL	no
LONGCHAR	Unknown value (?)
MEMPTR	A zero-length sequence of bytes
RAW	A zero-length sequence of bytes
RECID	Unknown value (?)
ROWID	Unknown value (?)
WIDGET-HANDLE	Unknown value (?)

If you are using the LIKE field option and you do not use the INITIAL constant option, the variable uses the initial value of the field or variable. In the DEFINE SHARED VARIABLE statement, the INITIAL option has no effect. However, the DEFINE NEW SHARED VARIABLE, the DEFINE NEW SHARED TEMP-TABLE, and the DEFINE NEW WORK-TABLE statements work with the INITIAL option.

LABEL string [ , string ] ...

The label you want to use when the variable is displayed. If you use the AS datatype option and you do not use the LABEL string option, the default label is the variable name. If you use the LIKE field option and you do not use the LABEL string option, the variable uses the label of the field or variable you name. You must enclose the string in quotes.

You can specify a label for each element in a determinate array variable. You cannot specify a label for elements in an indeterminate array variable.

In MS-Windows, you can designate a character within each label as a navigation mnemonic. Precede the character with an ampersand (&). When the variable is displayed with side labels, the mnemonic is underlined. The user can move focus to the variable by pressing ALT and the underlined letter. Navigation mnemonics operate only when you use side labels. If you specify more than one widget with the same mnemonic, Progress transfers focus to each of these in tab order when you make a selection.

Ending a label with an ampersand might produce unwanted behavior. To include a literal ampersand within a label, specify a double ampersand (&&).

MOUSE-POINTER expression

Specifies the default mouse pointer for the variable.

NO-UNDO

When the value of a variable is changed during a transaction and the transaction is undone, Progress restores the value of the variable to its prior value. If you do not want, or if you do not need, the value of a variable to be undone even when it has been changed during a transaction, use the NO-UNDO option with the DEFINE VARIABLE statement. NO-UNDO variables are efficient; use this option whenever possible.

Specifying NO-UNDO for a variable is especially useful if you want to indicate an error condition as the value of the variable, perform an UNDO, and later take some action based on that error condition. If one variable is defined LIKE another that is NO-UNDO, the second variable will be NO-UNDO only if you specify NO-UNDO in the definition of the second variable.

PFCOLOR expression

Specifies the prompt-for color for the variable in character interfaces. This option is ignored in graphical interfaces.

view-as-phrase

Specifies the default data representation widget for this variable. Following is the syntax for the view-as-phrase:

VIEW-AS { combo-box-phrase | editor-phrase | FILL-IN [ NATIVE ] [ size-phrase ] [ TOOLTIP tooltip ] | radio-set-phrase | selection-list-phrase | slider-phrase | TEXT [ size-phrase ] [ TOOLTIP tooltip ] | TOGGLE-BOX [ size-phrase ] [ TOOLTIP tooltip ] }

For more information on view-as-phrase, see the VIEW-AS phrase reference entry.

trigger-phrase

Defines triggers for the data representation widget specified in the view-as-phrase. Following is the syntax for the trigger-phrase:

TRIGGERS: { ON event-list [ ANYWHERE ] { trigger-block | PERSISTENT RUN proc-name [ IN handle ] [ ( input-parameters ) ] } } ... END [ TRIGGERS ]

For more information on triggers, see the Trigger phrase reference entry.

Examples

The r-dfvar.p procedure defines two variables, del and nrecs to be shared with procedure r-dfvar2.p. The del variable passes information to r-dfvar2.p, while nrecs passes information back to r-dfvar.p from r-dfvar2.p.

r-dfvar.p

DEFINE NEW SHARED VARIABLE del AS LOGICAL. DEFINE NEW SHARED VARIABLE nrecs AS INTEGER. del = no. MESSAGE "Do you want to delete the orders being printed (y/n)?" UPDATE del. RUN r-dfvar2.p. IF del THEN MESSAGE nrecs "Orders have been shipped and were deleted". ELSE MESSAGE nrecs "Orders have been shipped".

r-dfvar2.p

DEFINE SHARED VARIABLE del AS LOGICAL. DEFINE SHARED VARIABLE nrecs AS INTEGER. OUTPUT TO PRINTER. nrecs = 0. FOR EACH order WHERE ship-date <> ?: nrecs = nrecs + 1. FOR EACH order-line OF order: DISPLAY order-num line-num qty price. IF del THEN DELETE order-line. END. IF del THEN DELETE order. END. OUTPUT CLOSE.

The following example is a startup procedure. It defines a new global variable with the initial value TRUE and uses that variable to determine whether to run an initialization procedure, r-init.p, that displays sign-on messages. Then the global variable first-time is set to FALSE. If you restart this procedure during the same session (pressed STOP), r-init.p does not run again.

The procedure also defines the variable selection for entering menu choices within this procedure:

r-dfvar3.p

DEFINE NEW GLOBAL SHARED VARIABLE first-time AS LOGICAL INITIAL TRUE. DEFINE VARIABLE selection AS INTEGER FORMAT "9" LABEL "Selection". IF first-time THEN DO: RUN r-init.p. first-time = false. END. FORM " MAIN MENU " SKIP(1) "1 - Accounts Payable " SKIP "2 - Accounts Receivable" WITH CENTERED ROW 5 FRAME menu. REPEAT: VIEW FRAME menu. UPDATE selection AUTO-RETURN WITH FRAME sel CENTERED ROW 12 SIDE-LABELS. IF selection = 1 THEN DO: HIDE FRAME menu. HIDE FRAME sel. RUN apmenu.p. END. ELSE IF selection = 2 THEN DO: HIDE FRAME menu. HIDE FRAME sel. RUN armenu.p. END. ELSE DO: MESSAGE "Invalid selection. Try again". UNDO, RETRY. END. END.

The following procedure finds the day of the week of a date the user enters. The procedure defines an array with seven elements and uses the INITIAL option to define the initial value of each element in the array.

r-dfvar4.p

DEFINE VARIABLE dow AS CHARACTER FORMAT "x(9)" EXTENT 7 INITIAL ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]. DEFINE VARIABLE dob AS DATE INITIAL TODAY. REPEAT WITH SIDE-LABELS 1 DOWN CENTERED ROW 10 TITLE "Date of Birth": DISPLAY SKIP(1). UPDATE dob LABEL "Enter date of birth". DISPLAY dow[WEEKDAY(dob)] LABEL "It was a". END.

The following example defines a variable with a VIEW-AS phrase and a Trigger phrase:

r-defsel.p

DEFINE VARIABLE i AS INTEGER NO-UNDO. DEFINE VARIABLE clubs AS CHARACTER VIEW-AS SELECTION-LIST SIZE 20 BY 5 MULTIPLE SCROLLBAR-VERTICAL NO-DRAG LIST-ITEMS "One Iron", "Two Iron", "Three Iron", "Four Iron", "Five Iron", "Six Iron", "Seven Iron", "Eight Iron", "Nine Iron", "Pitching Wedge" LABEL "Golf Clubs Available" TRIGGERS: ON GO DO: IF SELF:SCREEN-VALUE <> "" THEN DO i = 1 TO NUM-ENTRIES(SELF:SCREEN-VALUE) : DISPLAY ENTRY(i, SELF:SCREEN-VALUE) FORMAT "X(16)" WITH FRAME clubs-sel CENTERED NUM-ENTRIES(SELF:SCREEN-VALUE) + 1 DOWN TITLE "Clubs Selected" USE-TEXT. DOWN 1 WITH FRAME clubs-sel. END. END. END TRIGGERS. ENABLE clubs WITH FRAME get-info TITLE "Select the Desired Club(s)". WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW.

Notes

You can use the DEFINE VARIABLE statement anywhere in a procedure. However, all references to the variable must appear after the DEFINE VARIABLE statement that defines it.
You cannot define a variable as a BLOB or CLOB field. You can define a variable using their MEMPTR and LONGCHAR counterparts, respectively.
Defining a LONGCHAR variable supports the same options as a CHARACTER variable, except for the FORMAT option and all VIEW-AS options except VIEW-AS EDITOR LARGE.
You should use the CASE-SENSITIVE option only when it is important to distinguish between uppercase and lowercase values entered for a character variable. For example, use CASE-SENSITIVE to define a variable for a part number that contains mixed uppercase and lowercase characters.
After you use the DEFINE NEW GLOBAL SHARED VARIABLE statement to create a global shared variable, use the DEFINE SHARED VARIABLE statements in other procedures to access that variable.
You cannot define the same global variable twice in the same OpenEdge session. If you try, and the definitions of the two variables do not match, Progress returns an error. If the definitions of the two variables match, Progress disregards the second variable you tried to define (if you are rerunning a startup procedure).
Changes made to variables when there is no active transaction are not undone when a block is undone.
When a procedure names and uses a shared variable:
Progress searches through the calling chain of procedures looking for the most recent DEFINE NEW SHARED VARIABLE statement that created that shared variable.
If no DEFINE NEW SHARED VARIABLE statement is found, Progress searches for a DEFINE NEW GLOBAL SHARED VARIABLE statement that created the shared variable.
If the procedure that names the shared variable is called from a trigger or internal procedure that is part of a persistent procedure context, the persistent context is also checked for the most recent DEFINE NEW SHARED VARIABLE or DEFINE NEW GLOBAL SHARED VARIABLE statement at the point in the calling chain where the trigger or internal procedure is executed.
If Progress finds one of these statements, it does not search any further for other statements that might have defined the same variable as NEW or NEW GLOBAL.
Progress checks the definition of a SHARED variable against that of the corresponding NEW SHARED or NEW GLOBAL SHARED variable. The data types and array extents must match. If the FORMAT, LABEL and DECIMALS specifications are not the same, each procedure uses its individual specification. The DEFINE NEW statement determines if a shared variable is NO-UNDO.
A SHARED variable remains in scope for an instance of a persistent procedure until the instance is deleted. This is true even if the original procedure that defined the variable as NEW SHARED goes out of scope while the procedure instance remains persistent.

If a trigger or internal procedure of a persistent procedure executes an external subprocedure that defines a SHARED variable, Progress includes the persistent procedure in the resolution of the corresponding NEW SHARED variable as though the procedure were on the procedure call stack.

If an application with several procedures defines a NEW SHARED variable with the same name in each procedure, Progress creates a different instance of the NEW SHARED variable in each procedure. This behavior supports recursive procedures and bill-of-materials applications.
You can neither define a SHARED or NEW SHARED variable, nor access such a variable defined in a procedure file, from within a class definition (.cls) file. If you do, Progress generates a compilation error. However, multiple procedure (.p) files can define and access an object reference variable for a class object instance as a NEW SHARED or NEW GLOBAL SHARED variable. In this case, the object reference variables must be defined for the same class (not a subclass or a super class) in all procedures that use them.
For SpeedScript, the following options are invalid: BGCOLOR, CONTEXT-HELP-ID, DCOLOR, FONT, FGCOLOR, MOUSE-POINTER, PFCOLOR, and view-as-phrase.

See also

DEFINE BUFFER statement, RUN statement, Trigger phrase, VIEW-AS phrase